[12.x] Add `config_or_fail` helper #56255

dallyger · 2025-07-10T09:34:27Z

Add getOrFail() to Config repository (with tests)
Add config_or_fail() helper in Foundation

The implementation should behave similarly to the
\Illuminate\Support\Env::getOrFail() method.

My use-case for this would be to quickly check, that the user did not forget to set some environment variables while deployment. Some configs may not have a good default value but are also not that important to block an entire deployment if just that small feature fails.

Example config:

# services.php

return [
  'xyz' => [
    'active' => (bool) env('XYZ_ACTIVE', false),
    'domain' => env('XYZ_DOMAIN'),
  ],
];

With that, you may use it like so:

if (config('services.xyz.active')) {
  Http::post(config_or_fail('services.xyz.domain').'/up');
}

The implementation should behave similarly to the `\Illuminate\Support\Env::getOrFail()` method.

macropay-solutions · 2025-07-10T10:26:03Z

src/Illuminate/Config/Repository.php

+     */
+    public function getOrFail(string $key)
+    {
+        return $this->get($key) ?? throw new RuntimeException("Configuration value for key [$key] is not set.");


if the config is actually null this will not be ok.

This is true, but also expected. If you know it may be null, you are probably better off using the regular get() method. As I said, this is similar to the env() helper.

What is your expectation on how the method should work? Only throw if the config key is missing? That would hardly be of any use, as most config keys should be static as they're build from the files in ./config/ returning arrays.

@macropay-solutions I've added my use case to the description so you may understand my intentions better now. What is your use case?

@dallyger in that case getNonNullOrFail would be a better naming.
We load all envs in a config dynamically and then we cache the config. We also use envs that are defined as null => configs that are defined as null.

I'm not totally convinced yet, because your example seems to deviate from the default out of the box experience. And if you know you do that you should know not to use that helper. I mean this does not change any existing behavior, only adds some small new feature.

Let's wait for some more feedback from other peoples and check what they think about it.

getOrFail is analog to findOrFail firstOrFail in db. If the row is there is should not throw. Analog if the config exists, no matter the value it should not throw.

You're right. Further testing showed me, that Env::getOrFail('FOO'), which this change was based upon, does return null, if FOO=null is set in .env. This was indeed an oversight on my end and due to a lot of indirection in the code not trivial to understand. Do you have suggestions for the error message and the helper function too? config_non_null_or_fail() seems like a rather long name for a small helper.

rojtjo

You could use this trick to allow null values.

It's done in multiple places throughout the framework such as here:

framework/src/Illuminate/Collections/Collection.php

Lines 175 to 196 in fac2d77

    
               /** 
        
                * Determine if an item exists in the collection. 
        
                * 
        
                * @param  (callable(TValue, TKey): bool)|TValue|string  $key 
        
                * @param  mixed  $operator 
        
                * @param  mixed  $value 
        
                * @return bool 
        
                */ 
        
               public function contains($key, $operator = null, $value = null) 
        
               { 
        
                   if (func_num_args() === 1) { 
        
                       if ($this->useAsCallable($key)) { 
        
                           $placeholder = new stdClass; 
        
                           return $this->first($key, $placeholder) !== $placeholder; 
        
                       } 
        
                       return in_array($key, $this->items); 
        
                   } 
        
                   return $this->contains($this->operatorForWhere(...func_get_args())); 
        
               }

rojtjo · 2025-07-10T12:42:28Z

src/Illuminate/Config/Repository.php

+     */
+    public function getOrFail(string $key)
+    {
+        return $this->get($key) ?? throw new RuntimeException("Configuration value for key [$key] is not set.");


Suggested change

return $this->get($key) ?? throw new RuntimeException("Configuration value for key [$key] is not set.");

$placeholder = new stdClass();

$value = $this->get($key, $placeholder);

if ($value === $placeholder) {

throw new RuntimeException("Configuration value for key [$key] is not set.");

}

return $value;

Thank you very much for this trick! However, I'm currently undecided on how I would like to proceed with this PR, as that would fix the issue mentioned above, but also deviate from my use case and no longer solve my issue. Will take some time to think about it.

rojtjo · 2025-07-10T12:43:01Z

src/Illuminate/Config/Repository.php

@@ -8,6 +8,7 @@
 use Illuminate\Support\Collection;
 use Illuminate\Support\Traits\Macroable;
 use InvalidArgumentException;
+use RuntimeException;



Suggested change

use stdClass;

shaedrich · 2025-07-10T13:25:13Z

config_or_fail

I don't know but this doesn't read well. It looks … clunky 🤔 Maybe, we should consider adapting conventions like Ruby (Laravel is based on Rails anyway) has (e.g. functionName? means, a boolean is returned, while object.methodName! means, the object is modified instead of immutably returned), although, I have no character at the top of my head to suggest right now

dallyger · 2025-07-10T13:30:20Z

For me personally, any style seems fine. Would be nice if they're consistent. My thought was, that there is a config_path() helper calling app()->configPath(). So I replicated the camel-case to snake-case conversion. But any other suggestion is welcome aswell.

macropay-solutions · 2025-07-10T19:41:24Z

@dallyger a solution for you only via macro would be the best. No headaches.

dallyger · 2025-07-11T07:44:55Z

@macropay-solutions Thank you! How could I not think about macros? I was literally using one on the same line! Also iterated on your suggestion for a name better matching the action it does.

My solution now is this:

use Illuminate\Support\Facades\Config;

# AppServiceProvider.php

Config::macro('getNonNull', fn (string $key) => Config::get($key)
    ?? throw new RuntimeException("Configuration value for key [$key] is empty."));
    
# usage:
Config::getNonNull('foo.bar');

donnysim · 2025-07-11T08:20:59Z

I get the point but I'm not following the reasoning. If you're deploying or expecting some config values to be set, checking them on runtime at the point of usage seems kind of dubious at best. You would check them all before doing anything (during bootstrapping etc.) to ensure nothing ends up partially broken or incorrect, not fail as it happens - especially on deployments. Most of those cases can be just written by

throw_unless(config('deploy.key'), new RuntimeException('Deploy key is not set.'));

or such where you can provide a more detailed error message if needed etc.. If you're conditionally throwing like in your example:

if (config('services.xyz.active')) {
  Http::post(config_or_fail('services.xyz.domain').'/up');
}

you'll most likely want to throw a custom exception that can be handled by the global exception handler or try/catch for that specific case.

dallyger added 2 commits July 10, 2025 11:28

[12.x] Add getOrFail() to Config repository

a21dddd

The implementation should behave similarly to the `\Illuminate\Support\Env::getOrFail()` method.

[12.x] Add config_or_fail helper

e2a3e58

macropay-solutions reviewed Jul 10, 2025

View reviewed changes

rojtjo reviewed Jul 10, 2025

View reviewed changes

dallyger marked this pull request as draft July 10, 2025 13:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[12.x] Add `config_or_fail` helper #56255

[12.x] Add `config_or_fail` helper #56255

dallyger commented Jul 10, 2025 •

edited

Loading

Uh oh!

macropay-solutions Jul 10, 2025

Uh oh!

dallyger Jul 10, 2025

Uh oh!

macropay-solutions Jul 10, 2025

Uh oh!

dallyger Jul 10, 2025

Uh oh!

macropay-solutions Jul 10, 2025

Uh oh!

dallyger Jul 10, 2025 •

edited

Loading

Uh oh!

rojtjo left a comment

Uh oh!

rojtjo Jul 10, 2025

Uh oh!

dallyger Jul 10, 2025

Uh oh!

rojtjo Jul 10, 2025 •

edited

Loading

Uh oh!

shaedrich commented Jul 10, 2025

Uh oh!

dallyger commented Jul 10, 2025

Uh oh!

macropay-solutions commented Jul 10, 2025

Uh oh!

dallyger commented Jul 11, 2025

Uh oh!

donnysim commented Jul 11, 2025

Uh oh!

Uh oh!

	/**
	* Determine if an item exists in the collection.
	*
	* @param (callable(TValue, TKey): bool)\|TValue\|string $key
	* @param mixed $operator
	* @param mixed $value
	* @return bool
	*/
	public function contains($key, $operator = null, $value = null)
	{
	if (func_num_args() === 1) {
	if ($this->useAsCallable($key)) {
	$placeholder = new stdClass;

	return $this->first($key, $placeholder) !== $placeholder;
	}

	return in_array($key, $this->items);
	}

	return $this->contains($this->operatorForWhere(...func_get_args()));
	}

-        return $this->get($key) ?? throw new RuntimeException("Configuration value for key [$key] is not set.");
+        $placeholder = new stdClass();
+        $value = $this->get($key, $placeholder);
+        if ($value === $placeholder) {
+            throw new RuntimeException("Configuration value for key [$key] is not set.");
+        }
+        return $value;

[12.x] Add config_or_fail helper #56255

Are you sure you want to change the base?

[12.x] Add config_or_fail helper #56255

Conversation

dallyger commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

macropay-solutions Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

dallyger Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

macropay-solutions Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

dallyger Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

macropay-solutions Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

dallyger Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rojtjo left a comment

Choose a reason for hiding this comment

Uh oh!

rojtjo Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

dallyger Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

rojtjo Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shaedrich commented Jul 10, 2025

Uh oh!

dallyger commented Jul 10, 2025

Uh oh!

macropay-solutions commented Jul 10, 2025

Uh oh!

dallyger commented Jul 11, 2025

Uh oh!

donnysim commented Jul 11, 2025

Uh oh!

Uh oh!

[12.x] Add `config_or_fail` helper #56255

[12.x] Add `config_or_fail` helper #56255

dallyger commented Jul 10, 2025 •

edited

Loading

dallyger Jul 10, 2025 •

edited

Loading

rojtjo Jul 10, 2025 •

edited

Loading